<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>RegExMatch</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>RegExMatch() <span class="ver">[v1.0.45+]</span></h1>

<p>Determines whether a string contains a pattern (regular expression).</p>

<pre class="Syntax">FoundPos := RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = &quot;&quot;, StartingPosition = 1])</pre>
<h3>Parameters</h3>
<dl>

  <dt>FoundPos</dt>
  <dd><p>RegExMatch() returns the position of the leftmost occurrence of <em>NeedleRegEx</em> in the string <em>Haystack</em>. Position 1 is the first character. Zero is returned if the pattern is not found. If an error occurs (such as a syntax error inside <em>NeedleRegEx</em>), an empty string is returned and ErrorLevel is set to one of the values <a href="#ErrorLevel">below</a> instead of 0.</p></dd>

  <dt>Haystack</dt>
  <dd><p>The string whose content is searched.</p></dd>

  <dt>NeedleRegEx</dt>
  <dd><p>The pattern to search for, which is a Perl-compatible regular expression (PCRE). The pattern's <a href="../misc/RegEx-QuickRef.htm#Options">options</a> (if any) must be included at the beginning of the string followed by a close-parenthesis. For example, the pattern &quot;<span class="red">i)</span>abc.*123&quot; would turn on the case-insensitive option and search for &quot;abc&quot;, followed by zero or more occurrences of any character, followed by &quot;123&quot;. If there are no options, the &quot;)&quot; is optional; for example, &quot;)abc&quot; is equivalent to &quot;abc&quot;.</p></dd>

  <dt>UnquotedOutputVar</dt>
  <dd><p><strong>Mode 1 (default):</strong> <em>OutputVar</em> is the unquoted name of a variable in which to store the part of <em>Haystack</em> that matched the entire pattern. If the pattern is not found (that is, if the function returns 0), this variable and all array elements below are made blank.</p>
      <p><a name="Array"></a>If any <a href="../misc/RegEx-QuickRef.htm#subpat">capturing subpatterns</a> are present inside <em>NeedleRegEx</em>, their matches are stored in a <a href="../misc/Arrays.htm#pseudo">pseudo-array</a> whose base name is <em>OutputVar</em>. For example, if the variable's name is <em>Match</em>, the substring that matches the first subpattern would be stored in <em>Match1</em>, the second would be stored in <em>Match2</em>, and so on. The exception to this is <a href="#NamedSubPat">named subpatterns</a>: they are stored by name instead of number. For example, the substring that matches the named subpattern &quot;(?P&lt;Year&gt;\d{4})&quot; would be stored in <em>MatchYear</em>. If a particular subpattern does not match anything (or if the function returns zero), the corresponding variable is made blank.</p>
      <p>Within a <a href="../Functions.htm">function</a>, to create a pseudo-array that is global instead of local, <a href="../Functions.htm#Global">declare</a> the base name of the pseudo-array (e.g. Match) as a global variable prior to using it. The converse is true for <a href="../Functions.htm#AssumeGlobal">assume-global</a> functions. However, it is often also necessary to declare each element, due to a <a href="../Functions.htm#ArrayConfusion">common source of confusion</a>.</p>      
      <p><a name="PosMode"></a><strong>Mode 2 (position-and-length):</strong> If a capital P is present in the RegEx's options -- such as &quot;<span class="red">P)</span>abc.*123&quot; -- the <em>length</em> of the entire-pattern match is stored in <em>OutputVar</em> (or 0 if no match). If any <a href="../misc/RegEx-QuickRef.htm#subpat">capturing subpatterns</a> are present, their positions and lengths are stored in two <a href="../misc/Arrays.htm#pseudo">pseudo-arrays</a>: <em>OutputVarPos</em> and <em>OutputVarLen</em>. For example, if the variable's base name is <em>Match</em>, the one-based <em>position</em> of the first subpattern's match would be stored in <em>MatchPos1</em>, and its length in <em>MatchLen1</em> (zero is stored in both if the subpattern was not matched or the function returns 0).  The exception to this is <a href="#NamedSubPat">named subpatterns</a>: they are stored by name instead of number (e.g. <em>MatchPosYear</em> and <em>MatchLenYear</em>).</p>
      <p id="ObjectMode"><strong>Mode 3 (match object)</strong> <span class="ver">[v1.1.05+]</span><strong>:</strong> If a capital O is present in the RegEx's options -- such as &quot;<span class="red">O)</span>abc.*123&quot; -- a <a href="#MatchObject">match object</a> is stored in <em>UnquotedOutputVar</em>. This object can be used to retrieve the position, length and value of the overall match and of each <a href="../misc/RegEx-QuickRef.htm#subpat">captured subpattern</a>, if present.</p>
    </dd>

  <dt>StartingPosition</dt>
  <dd><p>If <em>StartingPosition</em> is omitted, it defaults to 1 (the beginning of <em>Haystack</em>). Otherwise, specify 2 to start at the second character, 3 to start at the third, and so on. If <em>StartingPosition</em> is beyond the length of <em>Haystack</em>, the search starts at the empty string that lies at the end of <em>Haystack</em> (which typically results in no match).</p>
      <p>If <em>StartingPosition</em> is less than 1, it is considered to be an offset from the end of <em>Haystack</em>. For example, 0 starts at the last character and -1 starts at the next-to-last character. If <em>StartingPosition</em> tries to go beyond the left end of <em>Haystack</em>, all of <em>Haystack</em> is searched.</p>
      <p>Regardless of the value of <em>StartingPosition</em>, the return value is always relative to the first character of <em>Haystack</em>. For example, the position of &quot;abc&quot; in &quot;123abc789&quot; is always 4.</p></dd>

</dl>
<h3 id="ErrorLevel">ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This function is able to throw an exception on failure (not to be confused with &quot;no match found&quot;). For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to one of the following:</p>
<ul>
  <li>0, which means that no error occurred.</li>
  <li>A string in the following form: <em>Compile error N at offset M: description</em>. In that string, <em>N</em> is the PCRE error number, <em>M</em> is the position of the offending character inside the regular expression, and <em>description</em> is the text describing the error.</li>
  <li>A negative number, which means an error occurred during the <em>execution</em> of the regular expression. Although such errors are rare, the ones most likely to occur are &quot;too many possible empty-string matches&quot; (-22), &quot;recursion too deep&quot; (-21), and &quot;reached match limit&quot; (-8). If these happen, try to redesign the pattern to be more restrictive, such as replacing each * with a ?, +, or a limit like {0,3} wherever feasible.</li>
</ul>
<h3>Options</h3>
<p>See <a href="../misc/RegEx-QuickRef.htm#Options">Options</a> for modifiers such as &quot;<span class="red">i)</span>abc&quot;, which turns off case-sensitivity in the pattern &quot;abc&quot;.</p>
<h3 id="MatchObject">Match Object <span class="ver">v1.1.05+</span></h3>
<p>If a capital O is present in the RegEx's options, a match object is stored in <em>UnquotedOutputVar</em>. This object has the following properties:</p>
<p><strong>Match.Pos(N)</strong>: Returns the position of the overall match or a captured subpattern.</p>
<p><strong>Match.Len(N)</strong>: Returns the length of the overall match or a captured subpattern.</p>
<p><strong>Match.Value(N)</strong>: Returns the overall match or a captured subpattern.</p>
<p><strong>Match.Name(N)</strong>: Returns the name of the given subpattern, if it has one.</p>
<p><strong>Match.Count()</strong>: Returns the overall number of subpatterns.</p>
<p><strong>Match.Mark()</strong>: Returns the <em>NAME</em> of the last encountered <code>(*MARK:NAME)</code>, when applicable.</p>
<p><strong>Match[N]</strong>: If <em>N</em> is 0 or a valid subpattern number or name, this is equivalent to <code>Match.Value(N)</code>. Otherwise, <em>N</em> can be the name of one of the above properties. For example, <code>Match[&quot;Pos&quot;]</code> and <code>Match.Pos</code> are equivalent to <code>Match.Pos()</code> unless a subpattern named &quot;Pos&quot; exists, in which case they are equivalent to <code>Match.Value("Pos")</code>.</p>
<p><strong>Match.N</strong>: Same as above, except that <em>N</em> is an unquoted name or number.</p>
<p>For all of the above properties, <em>N</em> can be any of the following:</p>
<ul>
  <li>0 for the overall match.</li>
  <li>The number of a subpattern, even one that also has a name.</li>
  <li>The name of a subpattern.</li>
</ul>
<p>Brackets [] may be used in place of parentheses () if <em>N</em> is specified.</p>

<h3>Performance</h3>
<p>To search for a simple substring inside a larger string, use <a href="../Functions.htm#InStr">InStr()</a> because it is faster than RegExMatch().</p>
<p>To improve performance, the 100 most recently used regular expressions are kept cached in memory (in compiled form).</p>
<p>The <a href="../misc/RegEx-QuickRef.htm#Study">study option (S)</a> can sometimes improve the performance of a regular expression that is used many times (such as in a loop).</p>
<h3>Remarks</h3>
<p><a name="NamedSubPat"></a>A subpattern may be given a name such as the word <em>Year</em> in the pattern &quot;(?P&lt;Year&gt;\d{4})&quot;. Such names may consist of up to 32 alphanumeric characters and underscores. The following limitation does not apply to the &quot;O&quot; (match object) mode: Although named subpatterns are also available by their numbers during the RegEx operation itself (e.g. \1 is a backreference to the string that actually matched the first capturing subpattern), they are stored in the <a href="#Array">output pseudo-array</a> <em>only</em> by name (not by number). For example, if &quot;Year&quot; is the first subpattern, <em>OutputVarYear</em> would be set to the matching substring, but <em>OutputVar1</em> would not be changed at all (it would retain its previous value, if any). However, if an <a href="../misc/RegEx-QuickRef.htm#subpat">unnamed subpattern</a> occurs after &quot;Year&quot;, it would be stored in <em>OutputVar2</em>, not <em>OutputVar1</em>.</p>
<p>Most characters like abc123 can be used literally inside a regular expression. However, the characters <strong>\.*?+[{|()^$</strong> must be preceded by a backslash to be seen as literal. For example, <strong>\.</strong> is a literal period and <strong>\\</strong> is a literal backslash. Escaping can be avoided by using \Q...\E. For example: <code>\QLiteral Text\E</code>.</p>
<p>Within a regular expression, special characters such as tab and newline can be escaped with either an accent (`) or a backslash (\). For example, `t is the same as \t except when the <b>x</b> option is used.</p>
<p>To learn the basics of regular expressions (or refresh your memory of pattern syntax), see the <a href="../misc/RegEx-QuickRef.htm">RegEx Quick Reference</a>.</p>
<p>AutoHotkey's regular expressions are implemented using Perl-compatible Regular Expressions (PCRE) from <a href="http://www.pcre.org/">www.pcre.org</a>.</p>
<h3>Related</h3>
<p><a href="RegExReplace.htm">RegExReplace()</a>, <a href="../misc/RegEx-QuickRef.htm">RegEx Quick Reference</a>, <a href="../misc/RegExCallout.htm">Regular Expression Callouts</a>, <a href="../Functions.htm#InStr">InStr()</a>, <a href="IfInString.htm">IfInString</a>, <a href="StringGetPos.htm">StringGetPos</a>, <a href="../Functions.htm#SubStr">SubStr()</a>, <a href="SetTitleMatchMode.htm#RegEx">SetTitleMatchMode RegEx</a>, <a href="http://www.autohotkey.com/forum/topic16164.html">Global matching and Grep (forum link)</a></p>
<p>Common sources of text data: <a href="FileRead.htm">FileRead</a>, <a href="URLDownloadToFile.htm">UrlDownloadToFile</a>, <a href="../misc/Clipboard.htm">Clipboard</a>, <a href="GuiControls.htm#Edit">GUI Edit controls</a></p>
<h3>Examples</h3>
<pre class="NoIndent">FoundPos := RegExMatch(&quot;xxxabc123xyz&quot;, &quot;abc.*xyz&quot;)  <em>; Returns 4, which is the position where the match was found.</em>
FoundPos := RegExMatch(&quot;abc123123&quot;, &quot;123$&quot;)  <em>; Returns 7 because the $ requires the match to be at the end.</em>
FoundPos := RegExMatch(&quot;abc123&quot;, &quot;i)^ABC&quot;)  <em>; Returns 1 because a match was achieved via the case-insensitive option.</em>
FoundPos := RegExMatch(&quot;abcXYZ123&quot;, &quot;abc(.*)123&quot;, SubPat)  <em>; Returns 1 and stores &quot;XYZ&quot; in SubPat1.</em>
FoundPos := RegExMatch(&quot;abc123abc456&quot;, &quot;abc\d+&quot;, &quot;&quot;, 2)  <em>; Returns 7 instead of 1 due to StartingPosition 2 vs. 1.</em>

<em>; For general RegEx examples, see the <a href="../misc/RegEx-QuickRef.htm">RegEx Quick Reference</a>.</em></pre>

</body>
</html>
